PATH Mac OS X Server Documentation > Mac OS X Server Release Notes

NSDirectScreen

Inherits From: NSFramebuffer : NSSimpleBitmap : NSObject

Declared In: Interceptor/NSDirectScreen.h

Class Description

An NSDirectScreen is an object that can provide direct access to linearly mapped screen memory using a bitmap representation. The object provides mechanisms for taking screen control away from the WindowServer, determining supported hardware resolutions, and selecting a resolution. The object also provides a mechanism for manipulating the color palette for the display, when running in 8-bit pseudocolor mode. The NSDirectScreen object is intended for use in programs which take over the entire display from the Window Server and reconfigure the display.

The NSDirectScreen object is typically used by programs that implement an alternate window system, such as a MacOS application environment (Blue Box), or that need to take over the entire display and change it's resolution, such as Quake. These programs must preserve the existing state of the screen and receive events to be processed and passed on to their clients. NSDirectScreen assists in this by creating a non-retained window covering the entire display, and ordering the window on-screen above all other windows, including the desktop and menus.

The NSDirectScreen object provides a certain amount of system protection. If the client application terminates unexpectedly, NSDirectScreen and the Interceptor framework restore the display settings to the state expected by the Window Server, including the display mode and the default palette, and they remove the shielding window.

Setting Up an NSDirectScreen

A new NSDirectScreen is initialized with an NSScreen object that identifies the screen to be taken over. The Window Server must be running so that the NSDirectScreen object can obtain details on the screen layout and map the display memory into a program's address space. Programs that use the NSDirectScreen object can take over the display from the Window Server, but may not be used to replace the Window Server.

The NSDirectScreen object for a particular display does not permit changes to that display until the display has been shielded. Attempts to modify the display when it is not shielded will raise an NSDirectScreenDisplayIsUnshieldedException.

In normal operation, the application program sends the NSDirectScreen object a shieldDisplay message before modifying the display state. Once shielded, the application can modify the display mode or change the palette as needed. The application may request the shielding window, and use the window to receive mouse and keyboard events.

The following example demonstrates the steps involved in taking over the display and resetting it to for 640 x 480 pixel, 8-bit color operation.

NSDirectScreen *screen;
NSDictionary * mode;
screen = [[NSDirectScreen alloc] initWithScreen:[NSScreen mainScreen]];
mode = [screen bestModeForFormat:NSEightBitPseudoColor width:640 height:480];
[screen fadeDisplayOutToColor:[NSColor blackColor]];
[screen switchToDisplayMode:mode];
[screen fadeDisplayInFromColor:[NSColor blackColor]];

Mode Dictionary Keys and Values

NSDirectScreen uses mode dictionaries to select and configure the display mode. These NSDictionary objects use NSString objects as keys and NSNumber or NSString objects as values.

Key

Value Type

Description

NSDirectScreenHeight

NSNumber

Display height for this mode

NSDirectScreenWidth

NSNumber

Display width for this mode

NSDirectScreenDepth

NSNumber

Bits per pixel for this mode

NSDirectScreenColorSpace

NSString

Color space for this mode; a string defined in the NSColor class

NSDirectScreenPixelEncoding

NSString

NSString Pixel encoding. See the pixelEncoding method for a description

NSDirectScreenModeNumber

NSNumber

Internal value used in selecting display mode.

NSDirectScreenFrequency

NSNumber

May be missing for displays such as active matrix LCDs.

NSDirectScreenFrequencyRange

NSValue

(Optional)Encodes an NSRange for the minimum and maximum refresh rates.

NSDirectScreenSafeMode

NSNumber

(Optional)Indicates that this mode may be safely switched to without testing. The value is always 1.

NSDirectScreenDefaultMode

NSNumber

(Optional)Indicates that this is the default mode for the video hardware and attached display. The value is always 1.

NSDirectScreenRowBytes

NSNumber

Bytes per row of the display.

NSDirectScreenBitsPerPixel

NSNumber

Number of bits per pixel.

NSDirectScreenBitsPerSample

NSNumber

Bits per sample, or channel.

NSDirectScreenSamplesPerPixel

NSNumber

Samples or channels per pixel.

Key	Value Type	Description
NSDirectScreenHeight	NSNumber	Display height for this mode
NSDirectScreenWidth	NSNumber	Display width for this mode
NSDirectScreenDepth	NSNumber	Bits per pixel for this mode
NSDirectScreenColorSpace	NSString	Color space for this mode; a string defined in the NSColor class
NSDirectScreenPixelEncoding	NSString	NSString Pixel encoding. See the pixelEncoding method for a description
NSDirectScreenModeNumber	NSNumber	Internal value used in selecting display mode.
NSDirectScreenFrequency	NSNumber	May be missing for displays such as active matrix LCDs.
NSDirectScreenFrequencyRange	NSValue	(Optional)Encodes an NSRange for the minimum and maximum refresh rates.
NSDirectScreenSafeMode	NSNumber	(Optional)Indicates that this mode may be safely switched to without testing. The value is always 1.
NSDirectScreenDefaultMode	NSNumber	(Optional)Indicates that this is the default mode for the video hardware and attached display. The value is always 1.
NSDirectScreenRowBytes	NSNumber	Bytes per row of the display.
NSDirectScreenBitsPerPixel	NSNumber	Number of bits per pixel.
NSDirectScreenBitsPerSample	NSNumber	Bits per sample, or channel.
NSDirectScreenSamplesPerPixel	NSNumber	Samples or channels per pixel.

Limitations and Restrictions

The instance returned by the initWithScreen: method may not be the same as the instance that was sent the message. To avoid anomalous behavior, only one mapping of a specific frame buffer is permitted per task . VGA and SVGA frame buffers may not be mapped into the address space of a user task. These frame buffers are not capable of being mapped as a single linear address range, and require device-specific code to perform bank and plane switching.

Notes

<<Internal?>> API is provided to lock the framebuffer hardware into write, read, or read/write modes. This was originally added to support a bizarre framebuffer built into certain high-end RISC workstations. If Apple requires all framebuffers to be read/write accessible at all times, and there is no performance penalty for read/write vs write only access, then we can eliminate these APIs.

Method Types

Creating an NSDirectScreen: - initWithScreen:

Freeing an NSDirectScreen: - dealloc

Taking over a screen: - shieldDisplay
- shieldingWindow
- unshieldDisplay
- displayIsShielded

Fading the display in and out: - fadeDisplay:toColor:
- fadeDisplayOutToColor:
- fadeDisplayInFromColor:
- fadeDuration
- fadeInProgress
- fadeApplied
- setFadeDuration:

Selecting and switching display modes: - availableDisplayModes
- availableDisplayModesForOptions:
- switchToDisplayMode:
- bestModeForFormat:width:height:
- bestModeForOptions:

Accessing the palette: - canSetPalette; - currentPalette; - setPalette:
- setPaletteAtNextBlankingInterval:
Getting information about the bitmap: - bitsPerPixel
- samplesPerPixel
- bitsPerSample
- getPixelEncoding
- bytesPerRow
- colorSpaceName
- pixelEncoding
- pixelsWide
- pixelsHigh

Getting bitmap data: - addressForPoint:
- bitmapData

Getting information about the device driver: - deviceSlot
- deviceUnit
- driver

Instance Methods

addressForPoint

- (void *)addressForPoint:(NSPoint)location

Returns the address of the byte of the frame-buffer memory closest to location . For frame buffers with eight or more bits per pixel, the address will be the base address of the specified pixel. Location is specified as the offset from the upper left corner of the display, with the location .x value increasing to the right, and the location .y value increasing downward. Invoking this method while the display is not shielded raises an NSDirectScreenDisplayIsUnshieldedException.

availableDisplayModes

- (NSArray *)availableDisplayModes

Returns an array containing NSDictionary objects, each of which describes one of the available display modes. See "Mode Dictionary Keys and Values," above, for details.

See also: &endash; bestModeForFormat:width:height:, &endash; bestModeForOptions:, &endash; switchToDisplayMode:

availableDisplayModesForOptions:

- (NSArray *)availableDisplayModesForOptions:(NSDictionary *)options

Returns an NSArray of NSDictionary objects describing the available display modes which match the criteria specified in options . NSDirectScreen compares the contents of the options dictionary with all available modes, and puts in the returned array only modes that have the keys and values equal to the keys and values in options . If no matches are found, then an empty NSArray is returned. This method is useful for such things as finding all displays that support 8-bit pseudocolor, or which run at 640 x 480 pixel resolution.

See also: - availableDisplayModes, - availableDisplayModesForOptions:, switchToDisplayMode:

bestModeForFormat:width:height:

- (NSDictionary *)bestModeForFormat:(NSString *)format width:(int)width height:(int)height

Find a display mode with a depth suitable for or better than the specified pixel format , and with a width and height equal to or larger than width and height . The specified constraints will be matched as closely as possible, with pixel format matches preferred over width and height.

See also: - availableDisplayModes, - availableDisplayModesForOptions:, switchToDisplayMode:

bestModeForOptions:

- (NSDictionary *)bestModeForOptions:(NSDictionary *)options

Find a display mode meeting or exceeding the criteria specified by options . The options dictionary should contain only the keys used in mode dictionaries, with the appropriate types of values for each key. Only modes which match the specified keys and have values equal to or better than the values in options are candidates for the dictionary returned. NSDirectScreen attempts an exact match if possible. If no exact match is found, it attempts to match pixel format first (if specified) followed by width and height (if specified).

See also: - availableDisplayModes, - availableDisplayModesForOptions:, switchToDisplayMode:

bitsPerPixel

- (int)bitsPerPixel

Returns the number of bits allocated for each pixel in each plane of data. This is normally equal to the number of bits per sample or, if the data is in meshed configuration, the number of bits per sample times the number of samples per pixel. It can be another value in case extra memory is allocated for each pixel. This may be the case, for example, if pixel data is aligned on byte boundaries.

See also: &endash; bytesPerRow, &endash; pixelEncoding, &endash; samplesPerPixel

bitsPerSample

- (int)bitsPerSample

Returns the number of bits allocated for each sample in each plane of data.

See also: &endash; bytesPerRow, &endash; pixelEncoding, &endash; samplesPerPixel

bytesPerRow

- (int)bytesPerRow

Returns the number of bytes required to specify a scan line, that is, to move a pointer to a pixel at (X,Y) to point at a pixel (X,Y+1).

canSetPalette

- (BOOL)canSetPalette

Returns TRUE if the current display mode supports setting a hardware palette.

colorSpaceName

- (NSString *)colorSpaceName

Returns one of the following values, which indicate how bitmap data is to be interpreted:

NSDeviceBlackColorSpace

A gray scale between 1 (black) and 0 (white)

NSDeviceWhiteColorSpace

A gray scale between 0 (black) and 1 (white)

NSDeviceRGBColorSpace

Red, green, and blue color values

currentMode

- (NSDictionary *)currentMode

Return the mode dictionary describing the current display mode.

See also: - bestModeForFormat:width:height:

currentPalette

- (NSDirectPalette *)currentPalette

Return an instance of NSDirectPalette describing the current palette when running in 8-bit pseudocolor mode.

See also: - setPalette:, - setPaletteAtNextBlankingInterval:

bitmapData

- (unsigned char *)bitmapData

Returns a pointer to the frame buffer memory. The pointer refers to the lowest address in the frame buffer, located in the upper left corner of the screen rectangle by convention. Invoking this method while the display is not shielded raises a NSDirectScreenDisplayIsUnshieldedException.

deviceSlot

- (int)deviceSlot

Returns the Window Server's device-driver hardware slot number for the screen represented by the NSDirectScreen instance, if available from the implementation, or zero if the implementation does not support slot identifiers.

deviceUnit

- (int)deviceUnit

Returns the Window Server's device-driver unit or instance number for the screen represented by the NSDirectScreen instance.

displayIsShielded

- (BOOL)displayIsShielded

Returns whether if the display is currently shielded, if YES, your application is free to draw on the display.

driver

- (NSString *)driver

Returns the Window Server's device-driver name for the screen represented by the NSDirectScreen instance.

dealloc

- (void)dealloc

Deallocates the NSDirectScreen. This method also unmaps the mapped frame buffer, deallocates any conversion tables provided by the object, and destroys the Interceptor context associated with the NSDirectScreen.

fadeApplied

- (BOOL)fadeApplied

Returns whether a fade operation is in progress, or whether the display has already been faded to a solid color.

fadeDisplay:toColor:

- (void)fadeDisplay:(float)intensity toColor:(NSColor *)color

Performs a dissolve between the display contents and color by manipulating the hardware palette. An intensity of 1.0 corresponds to the normal display. An intensity of 0.0 corresponds to a display filled with color . Invoking this method while the display is not shielded raises a NSDirectScreenDisplayIsUnshieldedException. Invoking this method while the display is in a mode that does not support palette manipulation raises a NSDirectScreenDisplayCannotSetPaletteException. If this method is invoked with an intensity value less than 1.0, fadeApplied returns YES.

See also: - canSetPalette:, - displayIsShielded

fadeDisplayInFromColor:

- (void)fadeDisplayInFromColor:(NSColor *)color

Performs a series of dissolves over a one-second period from color to the display contents by manipulating the hardware palette. A key press or a mouse-button click jumps the fade to its end point immediately. Invoking this method while the display is not shielded raises an NSDirectScreenDisplayIsUnshieldedException. Invoking this method while the display is in a mode that does not support palette manipulation raises a NSDirectScreenDisplayCannotSetPaletteException. Until this operation is complete, fadeApplied and fadeInProgress return YES. A NSDirectScreenWillStartFadeInNotification is posted when the fade begins, and a NSDirectScreenDidFinishFadeInNotification is posted when the fade is complete.

See also: - canSetPalette:, - displayIsShielded

fadeDisplayOutToColor:

- (void)fadeDisplayOutToColor:(NSColor *)color

Performs a series of dissolves over one second from the display contents to color by manipulating the hardware palette. A key press or a mouse-button click will jump the fade to its end point immediately. Invoking this method while the display is not shielded raises a NSDirectScreenDisplayIsUnshieldedException. Invoking this method while the display is in a mode that does not support palette manipulation raises a NSDirectScreenDisplayCannotSetPaletteException. While this operation is in progress, fadeInProgress and fadeApplied return YES. On completion, fadeApplied returns YES. A NSDirectScreenWillStartFadeOutNotification is posted when the fade begins, and a NSDirectScreenDidFinishFadeOutNotification is posted when the fade is complete.

See also: - canSetPalette:, - displayIsShielded

fadeDuration

- (double)fadeDuration

Returns the duration of a fade operation in seconds.

fadeInProgress

- (BOOL)fadeInProgress

Returns whether a fadeDisplayInFromColor: or fadeDisplayOutToColor: operation is in progress.

initWithScreen:

- (NSDirectScreen *)initWithScreen:(NSScreen *)screen

Initializes the NSDirectScreen object to use the display screen. May return nil if the display hardware is not directly accessible (NeXTDimension board).

pixelEncoding

- (NSString *)pixelEncoding

Returns an NSString indicating the organization of data within a pixel. Each bit in the pixel is represented by one character. The first character in the string represents the most significant bit in the pixel.

The bit-type codes used for the pixel encoding string are:

Meaning

Code

Red channel data

'R'

Green channel data

'G'

Blue channel data

'B'

Alpha channel data

'A'

Gray channel data

`W' (1 is white colorspace)

Cyan channel data

`C'

Magenta channel data

`M'

Yellow channel data

`Y'

Black channel data

`K' (1 is black colorspace)

Luminance channel data

`l'

Chroma U channel data

'u'

Chroma V channel data

'v'

Chroma A channel data

'a'

Chroma B channel data

'b'

Pseudocolor

'P'

Bit set

`1'

Bit cleared

`0'

Bit skipped

`-'

Meaning	Code
Red channel data	'R'
Green channel data	'G'
Blue channel data	'B'
Alpha channel data	'A'
Gray channel data	`W' (1 is white colorspace)
Cyan channel data	`C'
Magenta channel data	`M'
Yellow channel data	`Y'
Black channel data	`K' (1 is black colorspace)
Luminance channel data	`l'
Chroma U channel data	'u'
Chroma V channel data	'v'
Chroma A channel data	'a'
Chroma B channel data	'b'
Pseudocolor	'P'
Bit set	`1'
Bit cleared	`0'
Bit skipped	`-'

samplesPerPixel

- (int)samplesPerPixel

Returns the number of components in the data. It includes both color components and the coverage component, if present.

screenNumber

- (int)screenNumber

Returns the screen number for the display represented by the NSDirectScreen instance.

screenSize

- (NSSize)screenSize

Returns the current screen size in pixels for the display represented by the NSDirectScreen instance.

setFadeDuration:

- (void)setFadeDuration:(double)seconds

Sets the duration of a fade operation in seconds. A value of zero seconds or less produces an instantaneous transition instead of a fade.

setPalette:

- (void)setPalette:(NSDirectPalette *)palette

Set the hardware palette to colors matching the entries in the palette. The change will take effect as soon as possible, based on the capabilities of the hardware.

setPaletteAtNextBlankingInterval:

- (void)setPaletteAtNextBlankingInterval:(NSDirectPalette)palette

Set the hardware palette to colors matching the entries in the palette. The change will take effect during the next vertical blanking period if possible, based on the capabilities of the hardware.

shieldDisplay

- (void)shieldDisplay

Shields the Display PostScript screen by constructing and ordering front a nonretained window; it also enables palette and display mode manipulation.

See also: - unshieldDisplay, - shieldingWindow

shieldingWindow

- (NSWindow *)shieldingWindow

Returns the shielding window if the display is shielded, or nil if the display is not shielded.

See also: - shieldDisplay, - unshieldDisplay

switchToDisplayMode:

- (void)switchToDisplayMode:(NSDictionary *)mode

Switches the display to the mode described by mode . Invoking this method while the display is not shielded raises an NSDirectScreenDisplayIsUnshieldedException.

See also: - availableDisplayModes, - bestModeForFormat:width:height:

unshieldDisplay

- (void)unshieldDisplay

Unshields the Display PostScript screen by destroying the shielding nonretained window; it also disables palette and display-mode manipulation, and restores the Display PostScript palette and display configuration.

See also: - shieldDisplay, - shieldingWindow

NSDeviceBlackColorSpace	A gray scale between 1 (black) and 0 (white)
NSDeviceWhiteColorSpace	A gray scale between 0 (black) and 1 (white)
NSDeviceRGBColorSpace	Red, green, and blue color values